home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / language / c / lcc / install.txt < prev    next >
Text File  |  1994-10-27  |  24KB  |  623 lines
  1. Installing lcc
  2. **************
  3.  
  4. Christopher W. Fraser
  5. AT&T Bell Laboratories Rm. 2C-464, 600 Mountain Ave., P.O. Box
  6. 636, Murray Hill, NJ 07974-0636
  7.  
  8. David R. Hanson
  9. Department of Computer Science, Princeton University, 35 Olden St.,
  10. Princeton, NJ 08544
  11.  
  12. Contents
  13. ========
  14.  
  15.  1. Introduction 
  16.  2. Paths 
  17.  3. Installing the Driver 
  18.  4. Installing the Compiler Proper 
  19.  5. Reporting Bugs 
  20.  6. Keeping in Touch 
  21.  
  22. 1. Introduction
  23. ===============
  24.  
  25. lcc is the ANSI C compiler described in our book A Retargetable C
  26. Compiler: Design and Implementation (Benjamin Cummings, 1995, ISBN
  27. 0-8053-1670-1).
  28.  
  29. Extract the distribution into its own directory. All paths below are relative to
  30. this directory. The distribution holds the following subdirectories. 
  31.  
  32. src 
  33.    source code 
  34. etc 
  35.    driver, man page 
  36. doc 
  37.    this document 
  38. include 
  39.    ANSI include files 
  40. tst 
  41.    test suite 
  42. mips-* mips-*/tst 
  43.    MIPS build area, test output 
  44. sparc-* sparc-*/tst
  45.    SPARC build area directory, test output 
  46. x86-dos x86-dos/tst
  47.    x86 build area, test output 
  48.  
  49. Distributions include code generators for the MIPS, SPARC, and the Intel
  50. 386 and its successors.
  51.  
  52. Installation involves three steps performed in the following order.
  53.  
  54.  1. Decide where to install the man page, the include files, the compiler,
  55.    and lcc, the driver program; see Sec. 2.
  56.  
  57.  2. Install a host-specific driver; see Sec. 3.
  58.  
  59.  3. Install the compiler; see Sec. 4.
  60.  
  61. The value of the variable rcsid in src/main.c identifies the version of
  62. the distribution. If the file LOG appears, it describes the changes from the
  63. previous version.
  64.  
  65. doc/install.html is the HTML file for this document. 
  66. doc/install.ps and doc/install.txt are PostScript and plain
  67. ASCII versions.
  68.  
  69. 2. Paths
  70. ========
  71.  
  72. Installation consists of three files and one directory; these are summarized
  73. below along with paths used in typical installations. 
  74.  
  75. /usr/local/man/man1/lcc.1 
  76.    the man page 
  77. /usr/local/lib/rcc 
  78.    the compiler 
  79. /usr/local/bin/lcc 
  80.    the driver 
  81. /usr/local/include/ansi 
  82.    include files (a directory) 
  83.  
  84. These files can be placed in other, site-specific locations, but the compiler
  85. should be named rcc. If the driver isn't named lcc, edit the man page (
  86. etc/lcc.1).
  87.  
  88. Include files are in directories named include/target-system; the
  89. meaningful combinations are 
  90.  
  91. mips-irix 
  92.    IRIX Release 4.0 
  93. mips-ultrix 
  94.    ULTRIX 4.3 
  95. sparc-sun 
  96.    SunOS 4.1 
  97. sparc-solaris 
  98.    Solaris 2.3 
  99. x86-dos 
  100.    DOS 6.0, Windows 3.1 
  101.  
  102. Choose the include files that are appropriate for your system, or make a
  103. copy of a closely related set and edit them.
  104.  
  105. For example, if the paths shown above are chosen and if 
  106. include/mips-ultrix has the appropriate include files, install the man
  107. page and include files by 
  108.  
  109. % cp etc/lcc.1 /usr/local/man/man1
  110. % cp include/mips-ultrix/*.h /usr/local/include/ansi
  111.  
  112. 3. Installing the Driver
  113. ========================
  114.  
  115. The preprocessor, compiler, assembler, and loader are invoked by a driver
  116. program, lcc, which is similar to cc on most systems. It's described in the
  117. man page etc/lcc.1. The driver is built by combining the
  118. host-independent part, etc/lcc.c, with a small host-specific part. By
  119. convention, host-specific parts are named hostname.c, where hostname
  120. is the local name for the host on which lcc is being installed. etc holds
  121. many examples. Comments in most give the details of the particular host;
  122. pick one that is closely related to your host, copy it to etc/yourhostname
  123. .c, and edit it as described below. You should not have to edit 
  124. etc/lcc.c.
  125.  
  126. Debug your version of the driver by running it with the -v -v options,
  127. which cause it to echo the commands it would execute, but not to execute
  128. them.
  129.  
  130. Here's etc/hart.c, which we'll use as an example in describing how to
  131. edit a host-specific part. This example illustrates all of the important
  132. features. 
  133.  
  134. /* DECStations running ULTRIX at Princeton University */
  135.  
  136. #include <string.h>
  137.  
  138. char *cpp[] = {
  139.         "/usr/gnu/lib/gcc-cpp", "-undef",
  140.         "-DLANGUAGE_C", "-D_LANGUAGE_C", "-D__LANGUAGE_C",
  141.         "-D_unix", "-D__unix", "-Dultrix", "-D_ultrix", "-D__ultrix",
  142.         "-Dmips", "-D_mips", "-D__mips",
  143.         "-Dhost_mips", "-D_host_mips", "-D__host_mips",
  144.         "-DMIPSEL", "-D_MIPSEL", "-D__MIPSEL",
  145.         "$1", "$2", "$3", 0 };
  146. char *include[] = { "-I/usr/local/include/ansi", 0 };
  147. char *com[] =  { "/usr/local/lib/rcc", "-target=mips-ultrix",
  148.         "$1", "$2", "$3", 0 };
  149. char *as[] =  { "/bin/as", "-o", "$3", "", "$1",
  150.         "-nocpp", "-EL", "$2", 0 };
  151. char *ld[] =  { "/usr/bin/ld", "-o", "$3", "/usr/lib/crt0.o",
  152.         "$1", "$2", "", "", "-lm", "-lc", 0 };
  153.  
  154. int option(arg) char *arg; {
  155.         if (strcmp(arg, "-g") == 0)
  156.                 as[3] = "-g";
  157.         else if (strcmp(arg, "-p") == 0
  158.         && strcmp(ld[3], "/usr/lib/crt0.o") == 0) {
  159.                 ld[3] = "/usr/lib/mcrt0.o";
  160.                 ld[7] = "/usr/lib/libprof1.a";
  161.         } else if (strcmp(arg, "-b") == 0
  162.         && access("/usr/local/lib/bbexit.o", 4) == 0)
  163.                 ld[6] = "/usr/local/lib/bbexit.o";
  164.         else
  165.                 return 0;
  166.         return 1;
  167. }
  168.  
  169. Most of the host-specific code is data that gives prototypes for the
  170. commands that invoke the preprocessor, compiler, assembler, and loader.
  171. Each command prototype is an array of pointers to strings terminated with
  172. a null pointer; the first string is the full path name of the command and the
  173. others are the arguments or argument placeholders, which are described
  174. below.
  175.  
  176. The cpp array gives the command for running the preprocessor. lcc is
  177. intended to be used with an ANSI preprocessor, such as the GNU C
  178. preprocessor available from the Free Software Foundation. If the GNU
  179. preprocessor is used, it must be named gcc-cpp in order for lcc's -N
  180. option to work correctly.
  181.  
  182. Literal arguments specified in prototypes, e.g., "-Dmips" in the cpp
  183. command above, are passed to the command as given.
  184.  
  185. The strings "$1", "$2", and "$3" in prototypes are placeholders for lists
  186. of arguments that are substituted in a copy of the prototype before the
  187. command is executed. $1 is replaced by the options specified by the user;
  188. for the preprocessor, this list always contains at least -Dunix and 
  189. -D__LCC__. $2 is replaced by the input files, and $3 is replaced by the 
  190. output file.
  191.  
  192. Zero-length arguments after replacement are removed from the argument
  193. list before the command is invoked. So, e.g., if the preprocessor is invoked
  194. without an output file, "$3" becomes "", which is removed from the final
  195. argument list.
  196.  
  197. For example, to specify a preprocessor command prototype to invoke 
  198. /bin/cpp with the options -Dmips and -Dultrix, the cpp array would
  199. be 
  200.  
  201. char *cpp[] = { "/bin/cpp", "-Dmips", "-Dultrix",
  202.         "$1", "$2", "$3", 0 };
  203.  
  204. The include array is a list of -I options that specify which directives
  205. should be searched to satisfy include directives. These directories are
  206. searched in the order given. The first directory should be the one to which
  207. the ANSI header files were copied in Sec. 2. The driver adds these options
  208. to cpp's arguments when it invokes the preprocessor, except when -N is
  209. specified.
  210.  
  211. Design this list carefully. Mixing ANSI and pre-ANSI headers (e.g., by
  212. listing /usr/include after the directory of ANSI headers shown above)
  213. may mix incompatible headers. Unless the default list holds only 
  214. /usr/include or only the ANSI headers, many users may be forced to
  215. use -N and -I incessantly.
  216.  
  217. com gives the command for invoking the compiler. This prototype can
  218. appear as shown above, with two important changes. The command name
  219. should be edited to reflect the location of the compiler chosen in Sec. 2,
  220. and the option -target=mips-ultrix should be edited to the target-
  221. system for your host. lcc can generate code for all of the target-system
  222. combinations listed in Sec. 2. The -target option specifies the default
  223. combination. The driver's -Wf option can be used to specify other
  224. combinations; the man page elaborates.
  225.  
  226. as gives the command for invoking the assembler.
  227.  
  228. ld gives the command for invoking the loader. For the other commands,
  229. the list $2 contains a single file; for ld, $2 contains all `.o' files and libraries,
  230. and $3 is a.out, unless the -o option is specified. As suggested in the
  231. code above, ld must also specify the appropriate startup code and default
  232. libraries.
  233.  
  234. The option function is described below; for now, use an existing option
  235. function or one that returns 0.
  236.  
  237. After specifying the prototypes, compile the driver by 
  238.  
  239. % cd etc
  240. % make HOST=hart
  241.  
  242. where hart is replaced by yourhostname. Run the resulting a.out with
  243. the options -v -v to display the commands that would be executed, e.g., 
  244.  
  245. % a.out -v -v foo.c baz.c mylib.a -lX11
  246. a.out $Revision: 3.1 $ $Date: 1994/09/07 11:37:52 $
  247. foo.c:
  248. /usr/gnu/lib/gcc-cpp -undef -DLANGUAGE_C -D_LANGUAGE_C -D__LANGUAGE_C
  249.    -D_unix -D__unix -Dultrix -D_ultrix -D__ultrix -Dmips -D_mips
  250.    -D__mips -Dhost_mips -D_host_mips -D__host_mips -DMIPSEL -D_MIPSEL
  251.    -D__MIPSEL -Dunix -D__LCC__ -v -I/usr/local/include/ansi foo.c
  252.    | /usr/local/lib/rcc -target=mips-ultrix -v - /tmp/lcc12511.s
  253. /bin/as -o foo.o -nocpp -EL /tmp/lcc12511.s
  254. baz.c:
  255. /usr/gnu/lib/gcc-cpp -undef -DLANGUAGE_C -D_LANGUAGE_C -D__LANGUAGE_C
  256.    -D_unix -D__unix -Dultrix -D_ultrix -D__ultrix -Dmips -D_mips
  257.    -D__mips -Dhost_mips -D_host_mips -D__host_mips -DMIPSEL -D_MIPSEL
  258.    -D__MIPSEL -Dunix -D__LCC__ -v -I/usr/local/include/ansi baz.c
  259.    | /usr/local/lib/rcc -target=mips-ultrix -v - /tmp/lcc12511.s
  260. /bin/as -o baz.o -nocpp -EL /tmp/lcc12511.s
  261. /usr/bin/ld -o a.out /usr/lib/crt0.o foo.o baz.o mylib.a -lX11 -lm -lc
  262. rm /tmp/lcc12511.s
  263.  
  264. Leading spaces indicate lines that have been folded manually to fit this
  265. page. Note the use of a pipeline to connect the preprocessor and compiler.
  266. lcc arranges this pipeline itself; it does not call the shell. If you want lcc
  267. to use temporary files instead of a pipeline, define PIPE=0 in CFLAGS
  268. when making the driver: 
  269.  
  270. % make CFLAGS='-DPIPE=0' HOST=hart
  271.  
  272. The option -pipe forces lcc to use a pipeline between the preprocessor
  273. and the compiler regardless of PIPE's value.
  274.  
  275. As the output shows, lcc places temporary files in /tmp. Alternatives can
  276. be specified by defining TEMPDIR in CFLAGS when making the driver, e.g., 
  277.  
  278. % make CFLAGS='-DTEMPDIR=\"/usr/tmp\"' HOST=hart
  279.  
  280. causes lcc to place temporary files in /usr/tmp. Once the driver is
  281. completed, install it by 
  282.  
  283. % cp a.out /usr/local/bin/lcc
  284.  
  285. where the destination is the location chosen for lcc in Sec. 2.
  286.  
  287. The option function is called for the options -g, -p, -pg, and -b
  288. because these compiler options might also affect the loader's arguments.
  289. For these options, the driver calls option(arg) to give the host-specific
  290. code an opportunity to edit the ld command, if necessary. option can
  291. change ld, if necessary, and return 1 to announce its acceptance of the
  292. option. If the option is unsupported, option should return 0.
  293.  
  294. For example, in response to -g, the option function shown above
  295. changes as[3] from "" to "-g", which specifies the debugging option to
  296. the assembler. If -g is not specified, the "" argument is omitted from the 
  297. as command because it's empty.
  298.  
  299. Likewise, the -p causes option to change the name of the startup code
  300. and add the name of the profiling library. Note that option has been
  301. written to support simultaneous use of -g and -p, e.g., 
  302.  
  303. % a.out -v -v -g -p foo.s baz.o -o myfoo
  304. a.out $Revision: 3.1 $ $Date: 1994/09/07 11:37:52 $
  305. /bin/as -o foo.o -g -nocpp -EL foo.s
  306. /usr/bin/ld -o myfoo /usr/lib/mcrt0.o foo.o baz.o
  307.    /usr/lib/libprof1.a -lm -lc
  308. rm /tmp/lcc12516.s
  309.  
  310. On Suns, the driver also recognizes -Bstatic and -Bdynamic as linker
  311. options, and recognizes but ignores Sun's `-target name' option.
  312.  
  313. The option -Woarg causes the driver to pass arg to option. Such options
  314. have no other effect; this mechanism is provided to support
  315. system-specific options that affect the commands executed by the driver.
  316.  
  317. The -b option causes the compiler to generate code to count the number
  318. of times each expression is executed. The exit function in 
  319. etc/bbexit.c writes these counts to prof.out when the program
  320. terminates. If option is called with -b, it must edit the ld command
  321. accordingly, as shown above. This version of option uses the access
  322. system call to insure that bbexit.o is installed before editing the ld
  323. command. To install bbexit.o execute 
  324.  
  325. % make bbexit.o
  326. % cp bbexit.o /usr/local/lib/bbexit.o
  327.  
  328. If necessary, change /usr/local/lib to reflect local conventions. The 
  329. exit function in etc/bbexit.c works on the systems listed in Sec. 2,
  330. but may need to be modified for other systems.
  331.  
  332. If option supports -b, you should also install etc/bprint.c, which
  333. reads prof.out and generates a listing annotated with execution counts.
  334. After lcc is installed, install bprint with the commands 
  335.  
  336. % make bprint
  337. % cp bprint /usr/local/bin/bprint
  338. % cp bprint.1 /usr/local/man/man1
  339.  
  340. The makefile uses lcc to compile bprint.c; you must use lcc or
  341. another ANSI C compiler, e.g., gcc, because bprint.c is written in ANSI
  342. C. Also, bprint.c includes "../src/profio.c", so it must be
  343. compiled in etc.
  344.  
  345. To complete the driver, write an appropriate option function for your
  346. system, and make and install the driver as described above.
  347.  
  348. 4. Installing the Compiler Proper
  349. =================================
  350.  
  351. The compiler proper, rcc, is built by compiling it with the host C compiler
  352. and then using the result to re-compile itself. A test suite is used to verify
  353. that the compiler is working correctly. The examples below illustrate this
  354. process on a MIPS under Ultrix. You must have the driver, lcc, installed in
  355. order to test rcc. If any of the steps below fail, contact us (see Sec. 5).
  356.  
  357. The object files, rcc, and the generated code for the programs in the test
  358. suite are placed in the directory target-system where target and system
  359. are the names of your target machine and its operating system,
  360. respectively. There are directories for the supported target-system
  361. combinations, e.g., mips-ultrix.
  362.  
  363. The default target in src/makefile is rcc. lcc is built by executing 
  364. make from the apppropriate target-system directory and specifying
  365. system-specific values for CFLAGS and LDFLAGS, if necessary. For
  366. example, to build rcc for a MIPS running Ultrix, execute the commands 
  367.  
  368. % cd mips-ultrix
  369. % make -f ../src/makefile
  370. cc -c -O ../src/alloc.c
  371. ...
  372. cc -c -O ../src/x86.c
  373. cc -o rcc  alloc.o bind.o dag.o ... mips.o sparc.o x86.o
  374.  
  375. There may be a few warnings, but there should be no errors. If your host is
  376. an SGI machine running IRIX 4.0 or later, you might need CFLAGS=-cckr.
  377. If cc doesn't automatically search the directory that holds the source file,
  378. specify CFLAGS=-I../src. If you use gcc, specify CFLAGS="-ansi
  379. -fno-builtin".
  380.  
  381. Once rcc is built with the host C compiler, run the test suite to verify that 
  382. rcc is working correctly. The commands in src/makefile run the shell
  383. script src/run on each C program in the test suite, tst/*.c. It uses the
  384. driver, lcc, so you must have the driver installed before testing rcc. The 
  385. target-system combination is read from the variable TARGET, which is
  386. specified when invoking make: 
  387.  
  388. % make -f ../src/makefile TARGET=mips-ultrix test
  389. ../rcc mips-ultrix 8q:
  390. ../rcc mips-ultrix array:
  391. ../rcc mips-ultrix cf:
  392. ../rcc mips-ultrix cq:
  393. ../rcc mips-ultrix cvt:
  394. ../rcc mips-ultrix fields:
  395. ../rcc mips-ultrix front:
  396. ../rcc mips-ultrix incr:
  397. ../rcc mips-ultrix init:
  398. ../rcc mips-ultrix limits:
  399. ../rcc mips-ultrix paranoia:
  400. ../rcc mips-ultrix sort:
  401. ../rcc mips-ultrix spill:
  402. ../rcc mips-ultrix stdarg:
  403. ../rcc mips-ultrix struct:
  404. ../rcc mips-ultrix switch:
  405. ../rcc mips-ultrix wf1:
  406. ../rcc mips-ultrix yacc:
  407.  
  408. For each C program in the test suite, src/run compiles the program and
  409. uses diff to compare the generated assembly code with the expected
  410. code (the MIPS code expected for tst/8q.c is in 
  411. mips-ultrix/tst/8q.s.bak, etc.). If there are differences, the script
  412. executes the generated code with the input given in tst (the input for 
  413. tst/8q.c is in tst/8q.0, etc.) and compares the output with the
  414. expected output (the expected output from tst/8q.c on the MIPS is in 
  415. mips-ultrix/tst/8q.1.bak, etc.). The script also compares the
  416. diagnostics from the compiler with the expected diagnostics.
  417.  
  418. On some systems, there may be a few differences between the generated
  419. code and the expected code. These differences occur because the
  420. expected code is generated by cross compilation on a MIPS and the
  421. least-significant bits of some floating-point constants differ from those bits
  422. in constants generated on your system. There should be no differences in
  423. the output from executing the test programs.
  424.  
  425. The ../rcc and mips-ultrix preceding the name of each test
  426. program in the output above indicate the compiler and the target, e.g., `
  427. ../rcc is generating code for a mips running the ultrix operating
  428. system.'
  429.  
  430. Next, build rcc again using the just-built rcc: 
  431.  
  432. % make -f ../src/makefile TARGET=mips-ultrix triple
  433. rm -f *.o
  434. make -f ../src/makefile CC='lcc -B./ -d0.1 -A'
  435.    CFLAGS='-Wf-target=mips-ultrix -I../src/../include/mips-ultrix
  436.    -I../src'  LDFLAGS=''
  437. lcc -B./ -d0.1 -A -c -Wf-target=mips-ultrix
  438.    -I../src/../include/mips-ultrix -I../src ../src/alloc.c
  439. ...
  440. lcc -B./ -d0.1 -A -o rcc  alloc.o bind.o dag.o decl.o ... x86.o
  441. strip rcc
  442. od +8 od2
  443. rm -f *.o
  444. make -f ../src/makefile CC='lcc -B./ -d0.1 -A'
  445.    CFLAGS='-Wf-target=mips-ultrix -I../src/../include/mips-ultrix
  446.    -I../src'  LDFLAGS=''
  447. lcc -B./ -d0.1 -A -c -Wf-target=mips-ultrix
  448.    -I../src/../include/mips-ultrix -I../src ../src/alloc.c
  449. ...
  450. lcc -B./ -d0.1 -A -o rcc  alloc.o bind.o dag.o decl.o ... x86.o
  451. strip rcc
  452. od +8 od3
  453. cmp od[23] && rm od[23]
  454.  
  455. This command builds rcc twice; once using the rcc built by cc and again
  456. using the rcc built by lcc. After building each version, an octal dump of
  457. the resulting binary is made, and the two dumps are compared. They
  458. should be identical, as shown at the end of the output above. If they aren't,
  459. our compiler is generating bad code; contact us.
  460.  
  461. The final version of rcc should also pass the test suite; i.e., the output
  462. from 
  463.  
  464. make -f ../src/makefile TARGET=mips-ultrix test
  465.  
  466. should be identical to that from the previous make test.
  467.  
  468. Now install the final version of rcc: 
  469.  
  470. % cp rcc /usr/local/lib/rcc
  471.  
  472. where the destination is the location chosen for rcc in Sec. 2.
  473.  
  474. On some systems, you may be able to use environment variables and 
  475. make's -e option to avoid specifying TARGET on each make command,
  476. and the make commands described above can be done with a single
  477. command: 
  478.  
  479. % setenv TARGET mips-ultrix
  480. % cd mips-ultrix
  481. % make -e -f ../src/makefile test triple test clean
  482.  
  483. make clean cleans up, but does not remove rcc, and make clobber
  484. cleans up and removes rcc.
  485.  
  486. The code generators for the other targets can be tested by running make
  487. from the appropriate target-specific directory and setting some
  488. environment variables to control what src/run does. For example, if you
  489. built mips-ultrix/rcc and installed it in /usr/local/lib/rcc, you
  490. can test the SPARC code generator for the SunOS operating system as
  491. follows. 
  492.  
  493. % setenv REMOTEHOST noexecute
  494. % setenv BUILDDIR /usr/local/lib/
  495. % cd sparc-sun
  496. % make -f ../src/makefile RCC= TARGET=sparc-sun test
  497. /usr/local/lib/rcc sparc-sun 8q:
  498. /usr/local/lib/rcc sparc-sun array:
  499. /usr/local/lib/rcc sparc-sun cf:
  500. /usr/local/lib/rcc sparc-sun cq:
  501. /usr/local/lib/rcc sparc-sun cvt:
  502. /usr/local/lib/rcc sparc-sun fields:
  503. /usr/local/lib/rcc sparc-sun front:
  504. /usr/local/lib/rcc sparc-sun incr:
  505. /usr/local/lib/rcc sparc-sun init:
  506. /usr/local/lib/rcc sparc-sun limits:
  507. /usr/local/lib/rcc sparc-sun paranoia:
  508. /usr/local/lib/rcc sparc-sun sort:
  509. /usr/local/lib/rcc sparc-sun spill:
  510. /usr/local/lib/rcc sparc-sun stdarg:
  511. /usr/local/lib/rcc sparc-sun struct:
  512. /usr/local/lib/rcc sparc-sun switch:
  513. /usr/local/lib/rcc sparc-sun wf1:
  514. /usr/local/lib/rcc sparc-sun yacc:
  515.  
  516. As above, src/run compares the SPARC code generated with what's
  517. expected. There should be no differences. Setting REMOTEHOST to 
  518. noexecute suppresses the assembly and execution of the generated
  519. code. BUILDDIR gives the directory that holds rcc, and specifying RCC=
  520. to make insures that rcc is not rebuilt in the sparc-sun directory.
  521.  
  522. If you set REMOTEHOST to the name of a SPARC machine to which you
  523. can rlogin, src/run will rcp the generated code to that machine and
  524. execute it there, if necessary. See src/run for the details.
  525.  
  526. Once everything is installed, you can use lcc as a cross compiler. The
  527. options -S and -Wf-target=target-system generate assembly code for
  528. the specified target, which is any of those listed in Sec. 2. For example, 
  529.  
  530. % lcc -Wf-target=sparc-sun -S tst/8q.c
  531.  
  532. generates SPARC code for tst/8q.c in 8q.s.
  533.  
  534. lcc can also generate code for a `symbolic' target. This target is used
  535. routinely in front-end development, and its output is a printable
  536. representation of the input program, e.g., the dags constructed by the front
  537. end are printed, and other interface functions print their arguments. You
  538. can specify this target with the option -Wf-target=symbolic. For
  539. example, 
  540.  
  541. % lcc -Wf-target=symbolic -S tst/8q.c
  542.  
  543. generates symbolic output for tst/8q.c in 8q.s. Finally, the option 
  544. -Wf-target=null specifies the `null' target for which lcc emits nothing
  545. and thus only checks the syntax and semantics of its inputs files.
  546.  
  547. 5. Reporting Bugs
  548. =================
  549.  
  550. lcc is a large, complex program. We find and repair errors routinely. If you
  551. think that you've found a error, follow the steps below, which are adapted
  552. from the instructions in Chapter 1 of A Retargetable C Compiler: Design
  553. and Implementation.
  554.  
  555.  1. If you don't have a source file that displays the error, create one.
  556.    Most errors are exposed when programmers try to compile a
  557.    program that they think valid, so you probably have a demonstration
  558.    program already.
  559.  
  560.  2. Preprocess the source file and capture the preprocessor output.
  561.    Discard the original code.
  562.  
  563.  3. Prune your source code until it can be pruned no more without
  564.    sending the error into hiding. We prune most error demonstrations
  565.    to fewer than five lines.
  566.  
  567.  4. Confirm that the source file displays the error with the distributed
  568.    version of lcc. If you've changed lcc, and if the error appears only
  569.    in your version, then you'll have to chase the error yourself, even if it
  570.    turns out to be our fault, because we can't work on your code.
  571.  
  572.  5. Annotate your code with comments that explain why you think that 
  573.    lcc is wrong. If lcc dies with an assertion failure, please tell us
  574.    where it died. If lcc crashes, please report the last part of the call
  575.    chain if you can. If lcc is rejecting a program that you think valid,
  576.    please tell us why you think it's valid, and include supporting page
  577.    numbers in the ANSI Standard, Appendix A in The C Programming
  578.    Language, 2nd edition by B. W. Kernighan and D. M. Ritchie
  579.    (Prentice Hall, 1988), or the appropriate section in C, A Reference
  580.    Manual, 3rd edition by S. B. Harbison and G. L. Steele, Jr. (Prentice
  581.    Hall, 1991). If lcc silently generates incorrect code for some
  582.    construct, please include the corrupt assembly code in the
  583.    comments and flag the bad instructions if you can.
  584.  
  585.  6. Confirm that your error hasn't been fixed already. The latest version
  586.    of lcc is always available for anonymous ftp from 
  587.    ftp.cs.princeton.edu in pub/lcc. A README file there gives
  588.    acquistion details, and a LOG file reports what errors were fixed and
  589.    when they were fixed. If you report a error that's been fixed, you
  590.    might get a canned reply.
  591.  
  592.  7. Send your program by electronic mail to 
  593.    lcc-bugs@cs.princeton.edu. Please send only valid C
  594.    programs; put all remarks in C comments so that we can process
  595.    reports semi-automatically.
  596.  
  597. 6. Keeping in Touch
  598. ===================
  599.  
  600. There is an lcc mailing list for general information about lcc. To be
  601. added to the list, send a message with the 1-line body 
  602.  
  603. subscribe lcc
  604.  
  605. to majordomo@cs.princeton.edu. This line must appear in the
  606. message body; `Subject:' lines are ignored. To learn more about mailing
  607. lists served by majordomo, send a message with the 1-word body 
  608. `help' to majordomo@cs.princeton.edu. Mail sent to 
  609. lcc@cs.princeton.edu is forwarded to everyone on the mailing list.
  610.  
  611. There is also an lcc-bugs mailing list for reporting bugs; subscribe to it by
  612. sending a message with the 1-line body 
  613.  
  614. subscribe lcc-bugs
  615.  
  616. to majordomo@cs.princeton.edu. Mail addressed to 
  617. lcc-bugs@cs.princeton.edu is forwarded to everyone on this list.
  618.  
  619.  
  620. Chris Fraser / cwf@research.att.com 
  621. David Hanson / drh@cs.princeton.edu 
  622. Thu Sep 8 10:14:42 EDT 1994 
  623.